Spec-Driven Development完全实战指南

前言

2025 年初,Andrej Karpathy 发了一条推文,创造了 Vibe Coding 这个词:

"我完全沉浸在 vibe 里,看到东西就说,说了就跑,跑完就复制粘贴,大部分都能用。遇到 bug 就把报错丢回去,不加任何评论。这不算真正的编程。"

这条推文引爆了整个 AI 编程社区。Vibe Coding 确实让所有人体验到了前所未有的编码速度——GitHub 的数据显示开发者完成任务快了约 55%。

但很快,一个残酷的现实浮出水面:三个月墙。

大量用 Vibe Coding 构建的项目在三个月后开始腐烂——没人理解生成的代码、修一个 bug 冒出三个新 bug、需求全散落在聊天记录里、重构率下降 60% 而复制粘贴率上升 48%。

于是,一种新的方法论开始在社区中成型:Spec-Driven Development(SDD)——不是让你放弃 AI 编程,而是让 AI 编程 真正可控、可维护、可协作。

如果用一句话概括:

SDD 的核心主张是:在 AI 编程时代,Spec(规格说明)而非代码,才是第一等公民。先写清楚要做什么,再让 Agent 去做。


1. 什么是 Spec-Driven Development

1.1 先说人话定义

Spec-Driven Development 是一种以 结构化规格说明 为核心驱动力的 AI 辅助开发方法论。

它的核心操作很简单:

在让 AI Agent 写任何一行代码之前,先把需求、设计、任务拆解写成可版本化的文档(Spec),然后让 Agent 按照 Spec 逐步实现、逐步验证。

这里的 Spec 不是传统意义上的"需求文档"——它是一份 Agent 可消费的、结构化的工作契约,通常包含:

1.2 SDD 的工作流

综合业界主流实践,SDD 的通用工作流可以归纳为五步:

Explore → Specify → Design → Implement → Verify
  ↑                                          |
  └────────────── 迭代反馈 ←──────────────────┘
  1. Explore(探索):让 AI 先读代码、理解现状,不写任何东西
  2. Specify(定义规格):写清楚要做什么、为什么做、边界在哪里
  3. Design(架构设计):数据模型、接口设计、技术选型、边界 case
  4. Implement(逐步实现):按任务拆解逐个实现,每个任务范围小且明确
  5. Verify(验证):对照 Spec 验证输出,测试内建在任务列表中

1.3 Birgitta Bockeler 的三层模型

Thoughtworks 的 Birgitta Bockeler 在 Martin Fowler 的网站上发表了目前最有深度的 SDD 分析,她把 SDD 分为三个层次:

层次 含义 适用场景
Spec-First 先写 Spec,实现后可以丢弃 单次功能开发,不需要长期维护 Spec
Spec-Anchored Spec 和代码一起维护,长期保持同步 团队协作项目,需要持续迭代
Spec-as-Source 只编辑 Spec,代码完全生成,人不碰代码 激进的全自动化场景(目前仍在探索中)

大多数团队目前处于 Spec-First 到 Spec-Anchored 之间。


2. Vibe Coding vs SDD:不是对立,而是光谱

2.1 一张表看懂两种模式

维度 Vibe Coding Spec-Driven Development
规划程度 几乎没有,边聊边做 充分的前期设计
核心制品 聊天记录(临时的、不可追溯) 版本化的 Spec 文件(持久的、可 Review)
速度曲线 前期极快,后期急剧下降 前期稍慢,后期稳定
适用周期 < 3 个月的项目 > 3 个月的项目
团队规模 一个人 多人协作
可维护性 差(三个月墙) 好(Spec 保留上下文和决策)
风险容忍度 高(原型、黑客松) 低(生产环境、有审计要求)

2.2 它们是互补的

业界共识正在收敛到一个务实的立场:Vibe Coding 和 SDD 不是非此即彼,而是同一条光谱上的两端。

最佳实践是:

切换信号——当你发现以下情况时,是从 Vibe 切到 SDD 的时候了:

Karpathy 自己的演进轨迹也印证了这一点——他在创造"Vibe Coding"一年后,转而倡导 Agentic Engineering,强调 "there is an art and science and expertise to it"。


3. 谁在用 SDD

3.1 关键人物

人物 身份 贡献
Andrew Ng DeepLearning.AI 创始人 与 JetBrains 合作推出 SDD 课程,将 SDD 推向主流视野
Paul Everitt JetBrains Developer Advocate 教授 DeepLearning.AI 的 SDD 课程,定义了 Constitution → Specification → Implementation → Validation → Replanning 工作流
Brian Madison Extend 高级工程经理 创建 BMad Method,25+ 年经验(美国陆军、NASA、IoT)。在团队里做了两周实验——所有工程师只能用 Agent 模式开发,独立发现了 SDD 原则
Birgitta Bockeler Thoughtworks 在 Martin Fowler 网站发表最深度的 SDD 工具分析,提出三层模型,也是目前最重要的批评声音
Andrej Karpathy 前 Tesla AI 总监 创造了 Vibe Coding 概念,一年后转向倡导 Agentic Engineering

3.2 公司和组织

GitHub:开源了 Spec Kit,一套 SDD 工具包,GitHub Stars 超过 137K。通过 specify CLI 提供 Constitution → Specify → Plan → Tasks → Implement 完整工作流,创建 .specify/ 目录管理 spec.md、plan.md、tasks.md 等文件。兼容 Copilot、Claude Code、Cursor、Codex。

AWS/Amazon:发布了 Kiro,一个内建 SDD 工作流的 Agentic IDE。在 IDE 层面原生支持 Requirements → Design → Tasks 的流程,不需要额外框架。

JetBrains:与 DeepLearning.AI 合作推出 SDD 课程,博客上有针对 Junie(他们的 AI Agent)的 SDD 实践指南。

Thoughtworks:将 SDD 纳入技术雷达,发表了 "Beyond Vibe Coding: The Five Building Blocks of AI-Native Engineering"。

Tessl:构建 Spec-as-Source 框架,追求最激进的路线——代码完全由 Spec 生成,文件头标注 // GENERATED FROM SPEC - DO NOT EDIT。

3.3 SDD 框架对比

框架 创建者 最适合 核心特点
Spec Kit GitHub 新项目 Constitution + Slash Commands,Agent 无关
BMad Method Brian Madison 有审计要求的项目 12+ AI Persona 多角色流水线,带审计追踪
OpenSpec Fission-AI 老项目改造 Delta 标记(ADDED/MODIFIED/REMOVED),77K+ npm 下载
Kiro AWS 通用开发 IDE 原生支持,不需要额外框架
Tessl Tessl Spec-as-Source tessl build 从 Spec 完全生成代码
SPEQ speq-ai 通用开发 专注开发者体验

4. 实战:在 Claude Code 中做 SDD

4.1 四阶段工作流

这是目前 Claude Code 社区沉淀出的最佳实践:

阶段一:Explore(探索)

让 Claude 先理解现有代码,不写任何东西:

> 读一下 src/ 目录的代码结构,理解下现在的架构,不要改任何东西

可以用 subagent 并行探索不同模块(数据层、API 层、UI 层),加速理解。

阶段二:Specify(写 Spec)

切换到 Plan Mode(Shift+Tab),让 Claude 帮你起草 Spec:

> 我要给系统加一个 XXX 功能,帮我写一份 Spec,包含:
> 1. 问题陈述和目标
> 2. 验收标准
> 3. 架构设计
> 4. 任务拆解(每个任务不超过 3 个文件)
> 5. 每个任务的完成定义
> 保存到 docs/spec-xxx.md

关键技巧:让 Claude 反过来 interview 你——它会问出你没想到的边界 case 和需求盲区。

阶段三:Implement(逐步实现)

按任务列表逐个执行,每个任务用独立的对话窗口(/clear 清上下文):

> 参考 docs/spec-xxx.md 的 Task 1,开始实现。完成后提交。

每完成一个任务就 /clear,保持上下文干净。可以用 subagent 并行处理无依赖的任务。

阶段四:Verify(验证)

测试内建在任务列表中,不是事后补的:

> 按照 docs/spec-xxx.md 的验收标准,逐条验证当前实现

4.3 上下文管理

这是 Claude Code 做 SDD 的命脉:


5. 实战:在 Cursor 中做 SDD

Cursor 社区沉淀出了一套基于 .cursor/rules/ 的四阶段规则文件方案:

规则文件 阶段 作用
@ears.mdc Specification AI 进入问答模式,追问范围、价值、边界 case,产出需求文档
@design.mdc Design 交互式设计研讨,覆盖架构、接口、数据流
@plan.mdc Planning 消费 Spec + Design,拆解 User Story 和 Backlog
@execute.mdc Execution 逐个 Story 实现,带 lint 和测试

最佳实践:


6. 实战:在 Codex 中做 SDD

OpenAI Codex 的 SDD 实践围绕 Backlog.md 展开:

  1. 在项目根目录维护一个 Backlog.md,列出所有待办任务
  2. 每个任务包含:描述、验收标准、涉及文件
  3. Codex Agent 从 Backlog 中取任务执行
  4. 社区工具 codex-spec 提供了自动化的 SDD 工作流

7. SDD 的现实挑战

7.1 Spec Drift(规格漂移)

这是 SDD 最核心的未解问题:Agent 在实现过程中会做适应性调整,但 Spec 文件不会自动更新,逐渐变成"文学作品"而非实际情况。

各框架的应对策略:

Bockeler 的结论是:最可靠的缓解方式仍然是 小步迭代。

7.2 过度规格化

Bockeler 在实测中发现,SDD 工具可能把一个简单的 bug fix 变成 4 个 User Story 配 16 条验收标准。她直言:

"I'd rather review code than all these markdown files."

解药:根据任务复杂度选择合适的规格深度。不是每件事都需要完整的 Spec-Design-Plan-Task 流水线。

7.3 "这不就是瀑布吗?"

社区中反复出现这个质疑。共识是:SDD 不等于瀑布,因为 Spec 被设计为可迭代的活文档。但 在实践中确实容易滑向瀑布——当团队过度投入前期规格而抗拒迭代时。

7.4 语义扩散

Bockeler 警告 SDD 这个词已经在经历"语义扩散"——不同人赋予它不同含义。有人把它等同于"写 PRD",有人等同于"用 TDD",有人等同于"Contract-First API 开发"。保持清晰的定义很重要。


8. 怎么选:一个决策框架

你的项目是原型/黑客松/一次性脚本吗?
  → 是:Vibe Coding,不要犹豫
  → 否 ↓

项目会活过三个月吗?
  → 不会:Vibe Coding + 轻量 Spec
  → 会 ↓

团队超过一个人吗?
  → 是:SDD(Spec-Anchored 级别)
  → 否 ↓

你需要上生产环境且有质量要求吗?
  → 是:SDD(至少 Spec-First 级别)
  → 否:Vibe Coding + 关键路径写 Spec

最务实的姿势:先 Vibe 出方向,再 Spec 落实现。


9. 核心参考资料

资料 来源
Andrej Karpathy 的 Vibe Coding 原始推文 Simon Willison 引用(2025.02)
DeepLearning.AI × JetBrains SDD 课程 deeplearning.ai
SDD 工具深度分析(三层模型) Birgitta Bockeler / Martin Fowler 网站
GitHub Spec Kit github.com/github/spec-kit
BMad Method(Tech Lead Journal #255) techleadjournal.dev
AWS Kiro IDE kiro.dev
Thoughtworks 技术雷达:SDD thoughtworks.com
Beyond Vibe Coding: Five Building Blocks Thoughtworks
Claude Code SDD 实战 gahmed.com
Cursor Rules SDD 方案 github.com/gertalot/cursor-rules
Codex SDD 工作流 jettro.dev
Spec Kit vs BMad vs OpenSpec 对比 dev.to/willtorber
Vibe Coding 技术债危机 TechStartups
SDD 学术论文 arXiv:2602.00180